/**
 * \addtogroup Camera Advanced Camera API
 * @{
 *  This file specifies the Samsung Advanced Camera API for Windows Mobile 
 *  devices.
 *
 *  Samsung's Advanced Camera API extends Microsoft's DirectShow API so that camera applications can 
 *  take advantage of advanced digital camera features.
 * 
 * The Advanced Camera API also enables you to switch between the primary rear-facing camera and the 
 * secondary front-facing camera on supported phones with dual cameras.
 *
 * Note: the features supported by the Advanced Camera API are generally only present on phones  
 * with high-end cameras, such as the Samsung Omnia.  Not all functionality is supported on all phones.
 *
 * Copyright &copy; 2009 Samsung Electronics
 *   
 * File: smiCamera.h
 */

#ifndef _SMI_CAMERA_H_
#define _SMI_CAMERA_H_

#include <atlbase.h>
#include <dshow.h>
#include <smiSDK.h>


/**
*  Specifies error codes specific to the Advanced Camera API.
*/
typedef enum 
{
    SMI_CAMERA_ERROR_AUTO_FOCUS_FAILED   =  SMI_CAMERA_RESULT_BASE,
	SMI_CAMERA_ERROR_VALUE_NOT_SUPPORTED =  SMI_CAMERA_RESULT_BASE + 1
} SmiCameraError;

/**
*  Specifies ISO values.
*/
typedef enum 
{
	SMI_CAMERA_ISO_AUTO,
	SMI_CAMERA_ISO_50,
	SMI_CAMERA_ISO_100,
	SMI_CAMERA_ISO_200,
	SMI_CAMERA_ISO_400,
	SMI_CAMERA_ISO_800
} SmiCameraISO;

/**
*  Specifies metering values.
*/
typedef enum 
{
	SMI_CAMERA_METERING_CENTER,
	SMI_CAMERA_METERING_MATRIX,
	SMI_CAMERA_METERING_SPOT
} SmiCameraMetering;

/**
*  Specifies autofocus values.
*/
typedef enum 
{
	SMI_CAMERA_AUTO_FOCUS_MODE_OFF,
	SMI_CAMERA_AUTO_FOCUS_MODE_NORMAL,
	SMI_CAMERA_AUTO_FOCUS_MODE_MACRO,
	SMI_CAMERA_AUTO_FOCUS_MODE_FACE
} SmiCameraAutoFocusMode;


/**
*  Specifies Camera Source values.
*/
typedef enum 
{
    /* Higher-end camera typically on the back of the phone. */
	SMI_CAMERA_ID_PRIMARY,

	/* Lower-end camera typically on the front of the phone, used for example for video conferencing. */
	SMI_CAMERA_ID_SECONDARY
} SmiCameraID;


/**
*  Specifies SMI camera handle, which is a video capture filter instance pointer. 
*  CComPtr<IBaseFilter> is defined by Microsoft's DirectShow API.
*/
typedef CComPtr<IBaseFilter> * smiCameraHandle;

/**
*  Specifies capabilities supported by the Advanced Camera API.
*/
typedef struct 
{
/**
 * Camera ISO setting support. TRUE if setting is supported, otherwise is FALSE.
*/
	BOOL isoIsSupported;

/**
 * Camera light metering support. TRUE if setting is supported, otherwise is FALSE.
*/
	BOOL meteringIsSupported;

/**
 * Camera autofocus support. TRUE if setting is supported, otherwise is FALSE.
*/
	BOOL autoFocusIsSupported;

/**
 * Camera Wide Dynamic Range (WDR) support. TRUE if setting is supported, otherwise is FALSE.
*/
	BOOL wdrIsSupported;

/**
 * Image stabilization support. TRUE if setting is supported, otherwise is FALSE.
*/
	BOOL imageStabilizationIsSupported;
} SmiCameraCapabilities;

/**
 * @deprecated [Deprecated in SDK 1.2.0 - use SmiCameraGetCapabilitiesEx instead.] 
 *
 * Gets the phone's camera capabilities.
 *
 * @param camHandle [in]		Video capture filter instance of the camera.
 * @param capabilities [out]	A pointer to the capabilities of the camera.
 *
 * @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if no camera is present on the phone 
 * \n							SMI_ERROR_INVALID_PARAMETER if capabilities is NULL or camHandle is NULL or invalid
 */ 
SMI_API SMI_RESULT SmiCameraGetCapabilities (smiCameraHandle camHandle, SmiCameraCapabilities *capabilities);

/**
 * Gets the phone's camera capabilities.
 * 
 * @param camId [in]		camera ID.
 * @param capabilities [out]	A pointer to the capabilities of the camera.
 *
 * @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if no camera is present on the phone 
 * \n							SMI_ERROR_INVALID_PARAMETER if capabilities is NULL or camHandle is NULL or invalid
 */ 
SMI_API SMI_RESULT SmiCameraGetCapabilitiesEx (SmiCameraID camId, SmiCameraCapabilities *capabilities);


/**
 * Sets the ISO setting of camera.
 * 
 * @param camHandle [in]		Video capture filter instance of the camera.
 * @param iso [in]				ISO value of the camera.
 *
 * @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_FEATURE_NOT_SUPPORTED if ISO setting is not supported
 * \n							SMI_ERROR_INVALID_PARAMETER if camhandle is NULL or invalid or iso is invalid 
 * \n							SMI_CAMERA_ERROR_VALUE_NOT_SUPPORTED if ISO value is not supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiCameraSetISO (smiCameraHandle camHandle, SmiCameraISO iso);

/**
 * Sets the metering setting of camera.
 * 
 * @param camHandle [in]		Video capture filter instance of the camera.
 * @param meter [in]			Metering value of the camera. 
 *
 * @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_FEATURE_NOT_SUPPORTED if metering setting is not supported
 * \n							SMI_ERROR_INVALID_PARAMETER if camera handle is NULL or invalid or meter value is invalid 
 * \n							SMI_CAMERA_ERROR_VALUE_NOT_SUPPORTED if meter value is not supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiCameraSetMetering (smiCameraHandle camHandle, SmiCameraMetering meter);

/**
 * Sets the autofocus setting of camera.
 * 
 * @param camHandle [in]		Video capture filter instance of the camera.
 * @param focus [in]			Focus value of the camera.
 *
 * @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_FEATURE_NOT_SUPPORTED if autofocus setting is not supported
 * \n							SMI_ERROR_INVALID_PARAMETER if video capture filter instance is NULL or invalid or focus value is invalid 
 * \n							SMI_CAMERA_ERROR_VALUE_NOT_SUPPORTED if focus value is not supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiCameraSetAutoFocusMode (smiCameraHandle camHandle, SmiCameraAutoFocusMode focus);

/**
 * Performs autofocus action on the camera.
 * 
 * Autofocus will be performed based on the mode set previously through the SmiCameraSetAutoFocusMode() API.
 *
 * Note: this method can take several seconds to complete, depending on light conditions and subject movement.
 *
 * @param camHandle [in]		Video capture filter instance of the camera.
 *
 * @return 
 *                              SMI_SUCCESS if autofocus succeeds
 * \n							SMI_CAMERA_ERROR_AUTO_FOCUS_FAILED if autofocus fails
 * \n							SMI_ERROR_FEATURE_NOT_SUPPORTED if autofocus setting is not supported
 * \n							SMI_ERROR_INVALID_PARAMETER if camera handle is NULL or invalid
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiCameraPerformAutoFocus(smiCameraHandle camHandle);

/**
 * Resets autofocus on the camera.
 * 
 * @param camHandle [in]		Video capture filter instance of the camera.
 *
 * @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_FEATURE_NOT_SUPPORTED if autofocus setting is not supported
 * \n							SMI_ERROR_INVALID_PARAMETER if camera handle is NULL or invalid
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiCameraResetAutoFocus(smiCameraHandle camHandle);

/**
 * Turns on WDR setting on the camera.
 * 
 * @param camHandle [in]		Video capture filter instance of the camera.
 *
 * @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_FEATURE_NOT_SUPPORTED if wdr setting is not supported
 * \n							SMI_ERROR_INVALID_PARAMETER if camera handle is NULL or invalid
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */  
SMI_API SMI_RESULT SmiCameraTurnOnWDR (smiCameraHandle camHandle);

/**
 * Turns off WDR setting on the camera.
 * 
 * @param camHandle [in] Video capture filter instance of the camera.
 *
 * @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_FEATURE_NOT_SUPPORTED if wdr setting is not supported
 * \n							SMI_ERROR_INVALID_PARAMETER if camera handle is NULL or invalid
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiCameraTurnOffWDR (smiCameraHandle camHandle);

/**
 * Turns on Image Stabilization setting on the camera.
 * 
 * @param camHandle [in]		Video capture filter instance of the camera.
 *
 * @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_FEATURE_NOT_SUPPORTED if image stabilization setting is not supported
 * \n							SMI_ERROR_INVALID_PARAMETER if camera handle is NULL or invalid
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiCameraTurnOnImageStabilization (smiCameraHandle camHandle);

/**
 * Turns off Image Stabilization setting on the camera.
 * 
 * @param camHandle [in]		Video capture filter instance of the camera.
 *
 * @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_FEATURE_NOT_SUPPORTED if image stabilization setting is not supported
 * \n							SMI_ERROR_INVALID_PARAMETER if camera handle is NULL or invalid
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiCameraTurnOffImageStabilization (smiCameraHandle camHandle);


/**
 * Creates the video capture filter instance for the given camera ID and loads the instance. 
 * 
 * Note: For more description, please refer programming guide
 * 
 * @param camId [in]			The camera ID.
 * @param camHandle [out]			Video capture filter instance of the camera.
 *
 * @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if primary/secondary camera is not present
 * \n							SMI_ERROR_INVALID_PARAMETER if camera ID or camHandle is invalid
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */
SMI_API SMI_RESULT SmiCameraOpen (SmiCameraID camId, smiCameraHandle camHandle);


/**
 * Releases the video capture filter instance and returns the system to the default state that was present 
 * before calling the SmiCameraOpen() API. 
 * 
 * @param camHandle [in]			Video capture filter instance of the camera.
 *
 * @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if camHandle is invalid
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */  
SMI_API SMI_RESULT SmiCameraClose (smiCameraHandle camHandle);



#endif /* _SMI_CAMERA_H_ */
/* @} */

